Skip to content

feat(agent-host): everything the Pi agent was missing - #197

Merged
deymosh merged 10 commits into
masterfrom
feat/pi-agent-tools
Nov 17, 2026
Merged

deymosh merged 10 commits into
masterfrom
feat/pi-agent-tools

Conversation

@deymosh

@deymosh deymosh commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Everything the Pi agent was missing next to Claude Code and OpenCode, in one PR. Pi ships four tools and leaves the rest to extensions; the CodeDeck Pi extension (the one that already held the permission gate) now adds what a session driven from a phone needs, using the cards and entries the phone already has for the other agents. No protocol, bridge or Android change.

What changed (one commit each)

  1. The extension is ordinary modules (drivers/pi/extension/), bundled by esbuild and carried in the host as text (__CODEDECK_PI_EXTENSION__, defined by build.mjs and vitest.config.mjs, so tests run what ships). It was one serialised function before.
  2. Fix: a provider profile's models got 128k context, no reasoning, 32k output whenever the endpoint's list stated no size (OpenCode Go's and most gateways' don't). Reported from the phone: OpenCode Go DeepSeek showed 128k instead of 1M, so Pi also compacted at ~128k with thinking off. Each profile model now borrows context, output limit, reasoning and input types from Pi's own catalog, matched on the id's last / segment, so a gateway (OpenCode Go/deepseek-v4.1-flash) works as well as a provider. The route's provider wins when Pi has it, otherwise the smallest context; a size the endpoint states still wins.
  3. Pi's ls, grep, find on. grep and find only where ripgrep/fd exist: Pi runs --offline and never downloads them. The image installs Debian's ripgrep and fd-find.
  4. todo (the checklist), ask (question card), Plan mode + exit_plan (plan card; approval switches to Ask or Auto edit). Plan mode refuses anything that writes, with a reason telling the model to present its plan. Its shell check is deliberately narrow: listed reading commands, none of their writing options, no redirection or substitution, and nothing that reads the environment.
  5. web_fetch: asks before every fetch, sends no cookies or credentials, follows at most 5 redirects (never into a local or private address the first URL didn't name), reads text only, frames the page as data.
  6. memory: per-project notes in Pi's home (never the working tree), indexed into each run's system prompt, written owner-only. Notes that look like secrets are refused, and notes are presented as background, not instructions.
  7. task sub-agents: a child Pi in RPC mode with the same extension. Every child tool call goes up to the driver as a permission request, decided by the session's mode, and its card names the sub-agent (PermissionRequest.subagent). The child's work shows under the call (OutputEntry.subagent). explore = read-only tools, so no cards; general = the session's tools. Several run in parallel.
  8. Background shells (bash_background, task_output, task_stop) as background tasks the phone can stop (supports.tasks now true). Start and end travel via pi.appendEntry → entry_appended, so a task can end after the turn. The phone's stop kills the process tree by pid.
  9. PowerShell: on Windows powershell is on beside bash. The extension asks Pi's own resolution whether a bash exists and switches bash off where it would only fail. Background shells use the session's shell, and Plan mode reads PowerShell syntax too.
  10. Docs: docs/PI.md, plus the fake model's new /task scenario in CLAUDE.md and the verify-changes skill.

How requests that wait for the phone travel: an extension editor dialog titled codedeck-request:<op> with JSON in and JSON out (extension/protocol.ts).

Decided not to include: LSP diagnostics (needs language servers per machine; first follow-up), checkpoint/rewind, ast-grep, web search (third-party service + keys).

Traffic cost

No new message kinds. Sub-agent work adds one entry per child tool call, result and reply, only while a sub-agent runs. A background task adds two entries (start and end). Nothing is streamed from a sub-agent's text deltas, only its finished replies.

Verification

  • ./codedeck check --changed: host typecheck, tests (165), build; Android bindings + gradle. ./codedeck e2e: green.
  • Live against real Pi 1.5.2 + the fake model: the 1M window through a gateway-style id, the question and plan cards, plan mode's refusal, a real child Pi whose command raises the parent's card tagged with the sub-agent, a background task outliving its turn, and one stopped from the phone (Windows: Git Bash + taskkill /T). Each new guard was broken once to see its test fail: catalog read, plan refusal, sub-agent gate.
  • A real background command in PowerShell on Windows / sh elsewhere.
  • Not verified: a real model through a gateway with reasoning on (needs the operator's router credentials), the PowerShell-only path on a Windows machine without Git Bash, and the phone UI on a device.

🤖 Generated with Claude Code

What review changed (folded into the commits that introduced each)

  • Plan mode's shell check: git grep -O (open matches in a pager — runs a program) is refused, alone or bundled (-nO); nothing that reads the environment passes in either shell — $ expansion, env:, a proc path, a process's environ file, or a glob inside a path that could spell them (cat /proc/self/env*).
  • web_fetch: localhost. (trailing dot) is an internal host; decimal and IPv4-mapped IPv6 forms are covered by tests.
  • A sub-agent that crashed or was stopped after saying something now fails its task call (its last reply kept as context) instead of passing that fragment off as its conclusion.
  • A background task stopped from the phone shows as stopped even when its shell traps the signal and exits 0.
  • A Windows CI failure: the extra-tools test read a Windows PATH with Linux rules; it now uses the host's own.

deymosh and others added 10 commits November 17, 2026 18:09
…odules

The extension Pi loads into every session was one function serialised with
Function.prototype.toString, so it could import nothing and had to stay
small. It now lives in drivers/pi/extension/ as ordinary modules (the
permission gate, the provider profile), bundled on its own by esbuild and
carried inside the agent host as text: build.mjs defines it as
__CODEDECK_PI_EXTENSION__, and vitest.config.mjs does the same, so the
test that drives the real Pi runs the extension a release ships. The driver
still writes it into Pi's home and passes it with -e; a host built without
it refuses the session rather than run Pi without the gate.

Pi maps @earendil-works/* and typebox to its own copies for extensions, so
the bundle leaves them external; a test checks the shipped text imports
nothing else. Behaviour is unchanged.

Co-Authored-By: Claude Code <[email protected]>
…talog

A provider profile's models were registered with Pi at a guess whenever
the endpoint's model list did not state a context size, which OpenCode
Go's and most gateways' do not: 128k context, 32k output, no reasoning.
A 1M-token DeepSeek then showed a 128k meter on the phone, Pi compacted
the conversation at about 128k, and thinking was off.

The extension now reads the running Pi's own model catalog
(`@earendil-works/pi-ai/providers/all`, which Pi provides to extensions)
and borrows each model's context, output limit, reasoning, thinking
levels and input types from it. The match is on the model, not the
endpoint, so it works for a gateway too: only the id's last `/` segment
is compared, a route that names one of Pi's providers (`OpenCode Go/` is
`opencode-go`) picks that provider's entry, and otherwise the smallest
context wins. A size the endpoint stated still wins; compatibility
switches are borrowed only from an entry on the same API; a model Pi does
not know keeps the old fallbacks.

The live test drives real Pi with a gateway-style id and expects the 1M
window; it fails at 128000 with the catalog read removed.

Co-Authored-By: Claude Code <[email protected]>
Pi enables only read, bash, edit and write unless its settings say
otherwise, so a model searched the tree through bash, and every search
raised a permission card in Ask mode. A session now adds Pi's own `ls`,
`grep` and `find` (as `--tools +name` entries, which keep whatever the
profile's defaultTools selects); all three are read-only and run without
a card, as they always did when an operator enabled them.

Pi's grep and find run ripgrep and fd from its own bin directory or PATH.
Pi runs `--offline`, so it never downloads them (its downloader fetches
the latest GitHub release unpinned); each tool is turned on only where its
binary is, since a tool that can only fail costs the model a call each
time it tries it. The bridge image installs Debian's ripgrep and fd-find,
whose `fdfind` Pi looks for too.

Co-Authored-By: Claude Code <[email protected]>
Pi ships no todo list, no way to ask the user and no plan mode; it leaves
them to extensions. The CodeDeck Pi extension now adds them, shown with
the cards the phone already has for the other agents:

- `todo`: the model writes its checklist whole (TodoWrite's shape); the
  driver shows each call as the phone's checklist, not as a tool row.
- `ask`: up to four questions with options or free text, shown as the
  question card; the answers go back as the tool's result.
- a Plan mode: the driver's gate refuses whatever could change something
  (Pi's read-only tools, a read-only shell command and the extension's own
  tools still run) with a reason that tells the model to present its plan;
  the extension tells the model it is in plan mode as each run starts;
  `exit_plan` shows the plan and the plan card, whose approval switches the
  session to Ask or Auto edit, or sends it back with the user's feedback.

Requests that wait for the phone travel as an extension `editor` dialog
titled `codedeck-request:<op>` with the request as JSON, answered with the
reply as JSON (extension/protocol.ts). The read-only shell check is
deliberately narrow: listed reading commands without their writing or
executing options (sort -o, rg --pre, fd -x, find -delete, git --output),
no redirection, substitution or background `&`, and no env/printenv, which
would put secrets into the transcript.

The fake model's question and plan scenarios now also call `ask` and
`exit_plan`; the live tests drive real Pi through both cards and plan
mode's refusal (which fails when plan mode allows everything).

Co-Authored-By: Claude Code <[email protected]>
Documentation, an issue or a changelog is often what a coding session
needs and nobody put in the workspace. The CodeDeck Pi extension adds
`web_fetch`: one http(s) URL read as text, which asks on the phone before
every fetch in Ask, Auto edit and Plan mode, like a command does.

It sends nothing that identifies the user: no cookies, no authorization,
no credentials in the URL, a fixed user agent. Redirects are followed by
hand, at most five, each hop held to the same rules; a public page may not
bounce the fetch into a local or private address (a router, a cloud
metadata service) that the card the user allowed never named. A body that
is not text is refused before it is read, a text body is cut at 5 MB and
the page at a size the model chose, and a timeout joins the turn's own
abort. HTML becomes readable text, and the result tells the model the page
is data from the web, not instructions.

Co-Authored-By: Claude Code <[email protected]>
A Pi session forgot everything when it ended, so the next one learned the
same decisions, preferences and gotchas again. The CodeDeck Pi extension
now keeps notes per project, the way Claude Code keeps its own: one
Markdown file per fact and a MEMORY.md index that every run's system
prompt carries, so a note is read only when it matters. The model saves,
updates and deletes notes with a `memory` tool; each save shows on the
phone as that call, so the user sees what is remembered.

The notes stay on the machine, in Pi's home rather than the working tree
(never in git), one store per project directory (its name plus a hash of
its path), written atomically, owner-only. A note that looks like it
holds a secret is refused, naming the kind but never the text: common
token shapes (OpenAI, GitHub, AWS, Slack, Google, Nostr nsec, JWT, private
key blocks) and the value of any secret-named variable in Pi's
environment. The prompt presents the notes as background to check against
the code, and an instruction inside a note as none the user gave.

Co-Authored-By: Claude Code <[email protected]>
Pi has no sub-agents of its own, and the one its examples ship runs each
child as a plain `pi -p` process: the child would load none of CodeDeck's
extension, so its tool calls would run without ever reaching the phone.

The CodeDeck Pi extension now adds `task`: a child Pi in RPC mode, with no
session file, loading the same extension in a sub-agent form (the gate
and the provider profile only, plus web_fetch for a general one). The
parent's tool is the child's RPC client:

- each tool call the child wants comes up through its gate and goes to the
  driver as a `permission` request, which the session's mode decides
  exactly as it decides the session's own calls; a card, when one is
  needed, names the sub-agent (PermissionRequest.subagent), and plan mode
  refuses the child's writes as it refuses the parent's;
- the child's tool calls, results and replies stream as the task call's
  progress, one numbered event per update, and the phone shows them under
  that call (OutputEntry.subagent), the child's call ids put under the
  parent's so parallel sub-agents never collide;
- its last reply is the task's result.

`explore` runs with the session's read-only built-ins only, so it can
change nothing and never needs a card; `general` gets the session's
built-ins. Several task calls in one message run in parallel (Pi's
default). The fake model gains `/task [brief]`, and the live test runs a
real child Pi whose command raises the parent's card tagged with the
sub-agent (it fails when the child answers its own gate).

Co-Authored-By: Claude Code <[email protected]>
Pi's bash holds the turn until a command ends, which a dev server or a
watcher never does. The CodeDeck Pi extension adds background shells:
`bash_background` starts a command in Pi's own shell (Git Bash on
Windows) and returns at once, asking like any command does;
`task_output` reads its newest output, optionally waiting for it to end;
`task_stop` stops it with everything it started.

The phone shows each as a background task (the catalog's
`supports.tasks` is now on for Pi). A task ends whenever it ends, often
after the turn, so its start and end travel as the extension's out-of-turn
events (pi.appendEntry, which Pi reports as entry_appended). The phone's
stop reaches the process directly: the driver kills the process tree by
the pid the start named (taskkill /T on Windows, the process group the
task leads elsewhere), and reports it stopped. Whatever still runs when Pi
exits is stopped with it; sub-agents get no background shells.

The fake model's `/background` prefers bash_background when an agent
offers it; the live tests run one past its turn and stop another from the
phone.

Co-Authored-By: Claude Code <[email protected]>
Pi has two shell tools: `bash` (Git Bash or a bash on PATH, on Windows)
and `powershell` (Windows only; PowerShell 7, else the Windows PowerShell
every Windows ships), and turns on only bash by default. A session now
works on whichever the machine has:

- on Windows the driver turns `powershell` on beside `bash`; as the
  session starts the extension asks Pi's own shell resolution whether it
  finds a bash (its environment, its shellPath setting) and switches bash
  off where it would only fail, leaving PowerShell as the session's shell;
- a background shell runs in the session's own shell — bash, or
  PowerShell where that is the only one — or whichever the model names
  with `shell`; a shell the machine lacks says which to use instead;
- Plan mode reads PowerShell too: listed reading cmdlets and their
  aliases (Get-ChildItem, Get-Content, Select-String, git's reading
  subcommands…), with no script block, subexpression, call operator,
  redirection, backtick, variable or env: drive, since the environment
  holds secrets.

The fake model's shell scenario knows Pi's `powershell`, and a test runs a
real background command in PowerShell on Windows and in sh elsewhere.

Co-Authored-By: Claude Code <[email protected]>
docs/PI.md now says what a Pi session has: Pi's ls, grep and find (where
ripgrep and fd are), PowerShell beside bash on Windows, Plan mode, and the
CodeDeck Pi extension's todo, ask, exit_plan, task, background shells,
web_fetch and memory, with what each asks and keeps. It also explains how
a provider profile's models borrow their context and reasoning from Pi's
own catalog, through a gateway too. The fake model's new `/task` scenario
and Pi's `/background` are listed where the other scenarios are
(CLAUDE.md and the verify-changes skill).

Co-Authored-By: Claude Code <[email protected]>
@deymosh
deymosh force-pushed the feat/pi-agent-tools branch from 35cedb4 to bdc4cbf Compare November 17, 2026 18:00
@deymosh
deymosh merged commit 9e83ae5 into master Nov 17, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant